From the PO.DAAC Cookbook, to access the GitHub version of the notebook, follow this link.

Search by HUC Example

Authors: Alireza Farahmand, Cassandra Nickles, PO.DAAC

Summary

This notebook will geospatially search using the PO.DAAC HUC Feature Translation Service (FTS), previewing (viusualizing) the queried region of interest (the Upper Tuolumne River Basin in the San Joaquin River Basin in California’s Sierra Nevada Mountains), and using FTS results to query NASA data. This is a programmatic approach to using the ‘Advanced Search -> River Reach’ query in the Earthdata Search GUI.

Requirements

1. Compute environment

This tutorial can be run in the following environments: - Local compute environment e.g. laptop, server: this tutorial can be run on your local machine - AWS instance running in us-west-2: NASA Earthdata Cloud data in S3 can be directly accessed via temporary credentials; this access is limited to requests made within the US West (Oregon) (code: us-west-2) AWS region.

2. Earthdata Login

An Earthdata Login account is required to access data, as well as discover restricted data, from the NASA Earthdata system. Thus, to access NASA data, you need Earthdata Login. Please visit https://urs.earthdata.nasa.gov to register and manage your Earthdata Login account. This account is free to create and only takes a moment to set up.

Learning Objectives

  1. use the FTS-HUC API (https://fts.podaac.earthdata.nasa.gov/) to define geographic region of interest (query by partial or exact HUC or HUC region name)
  2. visualize query
  3. use coordinates returned by FTS to query Sentinel-1 data, by polygon or bounding box.

Resources USGS Hydrologic unit map to help identifiy region of interest (e.g. HUC value or name) can be found here: https://water.usgs.gov/GIS/regions.html

Import libraries

import sys
import requests
import json
from shapely.geometry import box, Polygon
import matplotlib.pyplot as plt 
import geopandas as gpd
import numpy as np
import earthaccess

Search Feature Translation Service for Partial Region Matches

If you are unsure what the corresponding HUC is for your region of interest, you can query the FTS for partial region matches, by setting EXACT = FALSE.

# Querying partial matches with region "San Joaquin"
# This "partial" match is anything that BEGINS with the region specified.

REGION = "San Joa"
EXACT = False

# Query Feature Translation Service and parse JSON response
r = requests.get("https://fts.podaac.earthdata.nasa.gov/region/{}?exact={}".format(REGION, EXACT))

# Load response from FTS
response = r.json()

# Print all elements in HUC database that partially matches with region "San Jo"
print(json.dumps(response, indent = 4))
{
    "status": "200 OK",
    "time": "5.954 ms.",
    "hits": 3,
    "search on": {
        "parameter": "region",
        "exact": false,
        "polygon_format": "",
        "page_number": 1,
        "page_size": 100
    },
    "results": {
        "San Joaquin": {
            "USGS Polygon": {
                "Object URL": "https://podaac-feature-translation-service.s3-us-west-2.amazonaws.com/180400.zip",
                "Source": "ftp://rockyftp.cr.usgs.gov/vdelivery/Datasets/Staged/Hydrography/WBD/HU2/Shape/WBD_18_HU2_Shape.zip"
            },
            "Bounding Box": "-121.93679916804501,36.36688239563472,-118.65438684397327,38.757297326299295",
            "Convex Hull Polygon": "-120.63835246068544,36.36688239563472,-120.63808719818587,36.3669077091763,-118.73841884071788,37.07942819140368,-118.67420150956752,37.106490572611676,-118.6735564366519,37.10721677469388,-118.66992847311582,37.11265112260213,-118.65448236168146,37.14116804130782,-118.65438684397327,37.14146941734907,-118.65439289188998,37.14204016109818,-118.66449457312427,37.26170858174572,-118.76220691672262,37.45668952727641,-119.3277000731365,38.0651666159153,-119.68023816217266,38.44035645491624,-119.68779037986923,38.44773399761311,-119.84793537962065,38.5975748484222,-119.85336387752892,38.602501526539584,-119.85360401398685,38.60263670362269,-119.96183540965222,38.66278904519601,-119.96190132840212,38.662814343112586,-120.44062253078403,38.74564163360907,-120.48902702862557,38.753198735680655,-120.5539957670664,38.757297326299295,-120.99357654242573,38.71330113157592,-121.07883122250172,38.679223455587135,-121.0804450745826,38.678464784754965,-121.08111498187321,38.67810103163055,-121.5306744270087,38.43261620596991,-121.53113729471636,38.432277129928764,-121.8533769712995,38.059398593007586,-121.93679916804501,37.85678621415542,-121.02024189030101,36.55629579221568,-121.01674177780643,36.551948971389095,-121.00775647573704,36.54095870369781,-121.00754228094576,36.54077855369809,-120.90553311860407,36.477056078797034,-120.90373942485684,36.476002641298635,-120.73774029490619,36.387480222686065,-120.73704381990729,36.387168219561545,-120.63835246068544,36.36688239563472",
            "Visvalingam Polygon": "-120.54009506083798,38.751263262767,-120.64081991068161,38.70357532638269,-120.71727710431293,38.70154573055248,-120.74424469072943,38.67445884830289,-120.82514061977054,38.69750556180878,-120.85090918535553,38.634815070239426,-120.85764353951174,38.6677095441467,-120.96138979351736,38.674692672260846,-120.99357654242573,38.71330113157592,-121.0041938840759,38.682131000374284,-121.08583462874088,38.67462685351097,-121.08290462249539,38.62664741087707,-121.13917907969972,38.62357320671521,-121.2089503806331,38.49669539128712,-121.27717303990221,38.476062632985816,-121.26259156388318,38.44828171636226,-121.30028969090802,38.438934230960115,-121.32968337940406,38.39078809249321,-121.3599304720654,38.390321332077235,-121.44111079277275,38.43287303096952,-121.53153281971572,38.431799249721166,-121.51200092287104,38.3990511351887,-121.52198663431386,38.33135239571044,-121.49836688747553,38.271607430178165,-121.5407886280347,38.202546845910376,-121.6015964498153,38.14619380537283,-121.56855837590825,38.097723677323074,-121.66657562158946,38.09834799503045,-121.6994337861218,38.051017879478934,-121.74477304125975,38.03062196596892,-121.82191980051499,38.02152160869139,-121.86590229836338,37.98235407021048,-121.86986600564887,37.929583865084055,-121.93679916804501,37.85678621415542,-121.83044241300178,37.83564997147988,-121.73909092251853,37.760126577847075,-121.65209140390357,37.75944488930651,-121.65894963201794,37.70730379459576,-121.61490015812797,37.67537787797863,-121.62601494873576,37.621678591603654,-121.54111389574251,37.52994497299608,-121.50439590934116,37.525883816752355,-121.46914160210423,37.48928770118414,-121.45782723962179,37.39582026382925,-121.41146298448541,37.388361478424144,-121.40667140011789,37.314010806664555,-121.45952651357749,37.284674128585095,-121.39474167826137,37.15006367462735,-121.36483071268282,37.184255913115976,-121.33036383565297,37.167644427725065,-121.28572767738893,37.18259941936856,-121.24031638058443,37.158712379822305,-121.21668344207944,37.12189013821279,-121.231344697265,37.0835010684807,-121.20818868167595,37.061546638306424,-121.24711760557386,37.03114826752028,-121.24579035974261,36.988509275919796,-121.21167625146222,36.95729284888495,-121.23447995559349,36.92657608434928,-121.19828302127468,36.914258812493415,-121.15294869113671,36.865306701111024,-121.1143471828633,36.769056561677075,-121.04964033921374,36.75343970336803,-121.00617919865618,36.76372240960205,-120.95985347476977,36.720116577378064,-120.99658496742109,36.62860115564513,-121.03185423090798,36.58366134425654,-121.00807903927824,36.54150738807198,-120.83248069892579,36.471554128805565,-120.74546076156088,36.39178235497104,-120.68716579706802,36.39413058205071,-120.63835246068544,36.36688239563472,-120.6130646732247,36.441495923643856,-120.65738012628094,36.45709164132802,-120.66078854919232,36.51874457144066,-120.64111663047282,36.53968963494981,-120.66577184918458,36.58187674217595,-120.63374172840093,36.64829444832287,-120.5664488316304,36.71118111072525,-120.48434472967449,36.748263084626046,-120.44305652348856,36.749373372124296,-120.35291486008686,36.786035749150756,-120.23388445714659,36.767794575220705,-120.09885247506452,36.77904516791159,-119.97666310754585,36.8328416803281,-119.812517053634,36.84792405842967,-119.75333349122587,36.86578132194364,-119.69273040277824,36.92774011559749,-119.62802316329538,36.92294028747989,-119.57222072588195,36.95061687285363,-119.51664880721825,36.95427249159792,-119.46285424792671,36.981914174888345,-119.383642975133,37.05806398310352,-119.2715441169737,37.09415164138085,-119.20212414312311,37.10217027886836,-119.18784042960363,37.143694729845606,-119.0858305964286,37.176455095419726,-118.98052836534208,37.185962293321666,-118.89614518838971,37.208425149536765,-118.82732031245484,37.18283535165983,-118.73841884071788,37.07942819140368,-118.71628753554387,37.10699850281924,-118.67420150956752,37.106490572611676,-118.65448236168146,37.14116804130782,-118.68439308246838,37.24133370261069,-118.66449457312427,37.26170858174572,-118.71612671679412,37.328646110808506,-118.74006027092366,37.316221957702794,-118.78637329272675,37.343784711826686,-118.79007416876266,37.39395630133214,-118.7583354854786,37.444366181462215,-118.79668088958579,37.489443694933925,-118.84989162804482,37.47656995224554,-118.9163347623167,37.5501889677563,-118.99876110906376,37.569233157310066,-119.03902598191792,37.60352632600683,-119.03232058505336,37.62993357596582,-119.06525219021057,37.68462583317262,-119.12706784115625,37.73496690601115,-119.20027055354262,37.73524533309404,-119.2162143024762,37.71411237687687,-119.26841790031187,37.73950751954578,-119.20108320354137,37.801137019450096,-119.21512584414461,37.87042564434256,-119.19927543166921,37.88483115890352,-119.30948290962311,37.94616478068332,-119.30533157629623,38.02416955035392,-119.34927245018639,38.08565116171684,-119.54763344883679,38.14419101891764,-119.62908996641869,38.196015076128845,-119.61295248831874,38.2614448656106,-119.65148469659226,38.28643111453016,-119.62837932891978,38.349732117556925,-119.68113032050456,38.40217269768385,-119.68023816217266,38.44035645491624,-119.7679873151614,38.48571382776248,-119.77203659015515,38.518283566253615,-119.83374104110106,38.55282589953333,-119.85360401398685,38.60263670362269,-119.92262494617142,38.60820715882238,-119.96190132840212,38.662814343112586,-120.01568027831865,38.665510678525095,-120.06113182303977,38.63065420878752,-120.12165386565414,38.61454576089585,-120.1460215124913,38.64340277022609,-120.23913430193011,38.62996324108025,-120.24664128108515,38.65589799312335,-120.36064677465816,38.70485176492235,-120.39097328086109,38.70561956804619,-120.44062253078403,38.74564163360907,-120.54009506083798,38.751263262767",
            "HUC": "180400"
        },
        "San Joaquin 2": {
            "USGS Polygon": {
                "Object URL": "https://podaac-feature-translation-service.s3-us-west-2.amazonaws.com/1804.zip",
                "Source": "ftp://rockyftp.cr.usgs.gov/vdelivery/Datasets/Staged/Hydrography/WBD/HU2/Shape/WBD_18_HU2_Shape.zip"
            },
            "Bounding Box": "-121.93679916804501,36.36688239563472,-118.65438684397327,38.757297326299295",
            "Convex Hull Polygon": "-120.63835246068544,36.36688239563472,-120.63808719818587,36.3669077091763,-118.73841884071788,37.07942819140368,-118.67420150956752,37.106490572611676,-118.6735564366519,37.10721677469388,-118.66992847311582,37.11265112260213,-118.65448236168146,37.14116804130782,-118.65438684397327,37.14146941734907,-118.65439289188998,37.14204016109818,-118.66449457312427,37.26170858174572,-118.76220691672262,37.45668952727641,-119.3277000731365,38.0651666159153,-119.68023816217266,38.44035645491624,-119.68779037986923,38.44773399761311,-119.84793537962065,38.5975748484222,-119.85336387752892,38.602501526539584,-119.85360401398685,38.60263670362269,-119.96183540965222,38.66278904519601,-119.96190132840212,38.662814343112586,-120.44062253078403,38.74564163360907,-120.48902702862557,38.753198735680655,-120.5539957670664,38.757297326299295,-120.99357654242573,38.71330113157592,-121.07883122250172,38.679223455587135,-121.0804450745826,38.678464784754965,-121.08111498187321,38.67810103163055,-121.5306744270087,38.43261620596991,-121.53113729471636,38.432277129928764,-121.8533769712995,38.059398593007586,-121.93679916804501,37.85678621415542,-121.02024189030101,36.55629579221568,-121.01674177780643,36.551948971389095,-121.00775647573704,36.54095870369781,-121.00754228094576,36.54077855369809,-120.90553311860407,36.477056078797034,-120.90373942485684,36.476002641298635,-120.73774029490619,36.387480222686065,-120.73704381990729,36.387168219561545,-120.63835246068544,36.36688239563472",
            "Visvalingam Polygon": "-120.54009506083798,38.751263262767,-120.64081991068161,38.70357532638269,-120.71727710431293,38.70154573055248,-120.74424469072943,38.67445884830289,-120.82514061977054,38.69750556180878,-120.85090918535553,38.634815070239426,-120.85764353951174,38.6677095441467,-120.96138979351736,38.674692672260846,-120.99357654242573,38.71330113157592,-121.0041938840759,38.682131000374284,-121.08583462874088,38.67462685351097,-121.08290462249539,38.62664741087707,-121.13917907969972,38.62357320671521,-121.2089503806331,38.49669539128712,-121.27717303990221,38.476062632985816,-121.26259156388318,38.44828171636226,-121.30028969090802,38.438934230960115,-121.32968337940406,38.39078809249321,-121.3599304720654,38.390321332077235,-121.44111079277275,38.43287303096952,-121.53153281971572,38.431799249721166,-121.51200092287104,38.3990511351887,-121.52198663431386,38.33135239571044,-121.49836688747553,38.271607430178165,-121.5407886280347,38.202546845910376,-121.6015964498153,38.14619380537283,-121.56855837590825,38.097723677323074,-121.66657562158946,38.09834799503045,-121.6994337861218,38.051017879478934,-121.74477304125975,38.03062196596892,-121.82191980051499,38.02152160869139,-121.86590229836338,37.98235407021048,-121.86986600564887,37.929583865084055,-121.93679916804501,37.85678621415542,-121.83044241300178,37.83564997147988,-121.73909092251853,37.760126577847075,-121.65209140390357,37.75944488930651,-121.65894963201794,37.70730379459576,-121.61490015812797,37.67537787797863,-121.62601494873576,37.621678591603654,-121.54111389574251,37.52994497299608,-121.50439590934116,37.525883816752355,-121.46914160210423,37.48928770118414,-121.45782723962179,37.39582026382925,-121.41146298448541,37.388361478424144,-121.40667140011789,37.314010806664555,-121.45952651357749,37.284674128585095,-121.39474167826137,37.15006367462735,-121.36483071268282,37.184255913115976,-121.33036383565297,37.167644427725065,-121.28572767738893,37.18259941936856,-121.24031638058443,37.158712379822305,-121.21668344207944,37.12189013821279,-121.231344697265,37.0835010684807,-121.20818868167595,37.061546638306424,-121.24711760557386,37.03114826752028,-121.24579035974261,36.988509275919796,-121.21167625146222,36.95729284888495,-121.23447995559349,36.92657608434928,-121.19828302127468,36.914258812493415,-121.15294869113671,36.865306701111024,-121.1143471828633,36.769056561677075,-121.04964033921374,36.75343970336803,-121.00617919865618,36.76372240960205,-120.95985347476977,36.720116577378064,-120.99658496742109,36.62860115564513,-121.03185423090798,36.58366134425654,-121.00807903927824,36.54150738807198,-120.83248069892579,36.471554128805565,-120.74546076156088,36.39178235497104,-120.68716579706802,36.39413058205071,-120.63835246068544,36.36688239563472,-120.6130646732247,36.441495923643856,-120.65738012628094,36.45709164132802,-120.66078854919232,36.51874457144066,-120.64111663047282,36.53968963494981,-120.66577184918458,36.58187674217595,-120.63374172840093,36.64829444832287,-120.5664488316304,36.71118111072525,-120.48434472967449,36.748263084626046,-120.44305652348856,36.749373372124296,-120.35291486008686,36.786035749150756,-120.23388445714659,36.767794575220705,-120.09885247506452,36.77904516791159,-119.97666310754585,36.8328416803281,-119.812517053634,36.84792405842967,-119.75333349122587,36.86578132194364,-119.69273040277824,36.92774011559749,-119.62802316329538,36.92294028747989,-119.57222072588195,36.95061687285363,-119.51664880721825,36.95427249159792,-119.46285424792671,36.981914174888345,-119.383642975133,37.05806398310352,-119.2715441169737,37.09415164138085,-119.20212414312311,37.10217027886836,-119.18784042960363,37.143694729845606,-119.0858305964286,37.176455095419726,-118.98052836534208,37.185962293321666,-118.89614518838971,37.208425149536765,-118.82732031245484,37.18283535165983,-118.73841884071788,37.07942819140368,-118.71628753554387,37.10699850281924,-118.67420150956752,37.106490572611676,-118.65448236168146,37.14116804130782,-118.68439308246838,37.24133370261069,-118.66449457312427,37.26170858174572,-118.71612671679412,37.328646110808506,-118.74006027092366,37.316221957702794,-118.78637329272675,37.343784711826686,-118.79007416876266,37.39395630133214,-118.7583354854786,37.444366181462215,-118.79668088958579,37.489443694933925,-118.84989162804482,37.47656995224554,-118.9163347623167,37.5501889677563,-118.99876110906376,37.569233157310066,-119.03902598191792,37.60352632600683,-119.03232058505336,37.62993357596582,-119.06525219021057,37.68462583317262,-119.12706784115625,37.73496690601115,-119.20027055354262,37.73524533309404,-119.2162143024762,37.71411237687687,-119.26841790031187,37.73950751954578,-119.20108320354137,37.801137019450096,-119.21512584414461,37.87042564434256,-119.19927543166921,37.88483115890352,-119.30948290962311,37.94616478068332,-119.30533157629623,38.02416955035392,-119.34927245018639,38.08565116171684,-119.54763344883679,38.14419101891764,-119.62908996641869,38.196015076128845,-119.61295248831874,38.2614448656106,-119.65148469659226,38.28643111453016,-119.62837932891978,38.349732117556925,-119.68113032050456,38.40217269768385,-119.68023816217266,38.44035645491624,-119.7679873151614,38.48571382776248,-119.77203659015515,38.518283566253615,-119.83374104110106,38.55282589953333,-119.85360401398685,38.60263670362269,-119.92262494617142,38.60820715882238,-119.96190132840212,38.662814343112586,-120.01568027831865,38.665510678525095,-120.06113182303977,38.63065420878752,-120.12165386565414,38.61454576089585,-120.1460215124913,38.64340277022609,-120.23913430193011,38.62996324108025,-120.24664128108515,38.65589799312335,-120.36064677465816,38.70485176492235,-120.39097328086109,38.70561956804619,-120.44062253078403,38.74564163360907,-120.54009506083798,38.751263262767",
            "HUC": "1804"
        },
        "San Joaquin Delta": {
            "USGS Polygon": {
                "Object URL": "https://podaac-feature-translation-service.s3-us-west-2.amazonaws.com/18040003.zip",
                "Source": "ftp://rockyftp.cr.usgs.gov/vdelivery/Datasets/Staged/Hydrography/WBD/HU2/Shape/WBD_18_HU2_Shape.zip"
            },
            "Bounding Box": "-121.93679916804501,37.50128378554052,-120.83793204891731,38.21666854588847",
            "Convex Hull Polygon": "-121.48401321978946,37.50128378554052,-121.48319938333242,37.501357755332094,-121.48196255312598,37.50148574804024,-121.05388696212378,37.76071366013787,-120.90450576548068,38.0272342086825,-120.90349268423222,38.02938314201248,-120.83793204891731,38.18877460322341,-120.83800179891722,38.1976922021679,-120.83898908849903,38.19987750528952,-121.02443172883619,38.21666854588847,-121.02474798300238,38.21663954068015,-121.02495458821039,38.216620591721835,-121.61499185396116,38.10789443147394,-121.6671072070053,38.09826675128056,-121.84538162652024,38.06328592216818,-121.85283117130035,38.05978179300695,-121.8533769712995,38.059398593007586,-121.93679916804501,37.85678621415542,-121.56421756653998,37.54766027817686,-121.54682447177532,37.53336393132406,-121.54584872802684,37.53266251257514,-121.54544794886078,37.532376185492296,-121.54202411449108,37.53037829903707,-121.49308462915042,37.502441020955416,-121.48639323541079,37.501483144915255,-121.48560074791203,37.501374500123745,-121.48401321978946,37.50128378554052",
            "Visvalingam Polygon": "-121.02143199238253,38.21228919277024,-121.03881544131383,38.21370070526808,-121.05832012565855,38.19822062820873,-121.07285287251102,38.19676138550267,-121.11744717765015,38.17114820429242,-121.14022114948978,38.168721211587865,-121.15031440780746,38.15854012306204,-121.20154061397795,38.143356763710585,-121.27375955553254,38.116192127294426,-121.32007884504395,38.108511572097996,-121.33525729293706,38.09480684191095,-121.35392083665806,38.08854727525397,-121.41605480843663,38.087353247130864,-121.44424249485121,38.08399005338606,-121.4631167833636,38.071604213821956,-121.4724672395991,38.08759970546379,-121.50203907184482,38.091632609624185,-121.5035856697591,38.072714664861905,-121.51886918848538,38.089077872128144,-121.53291849575527,38.091567440874314,-121.56947503215684,38.08615950442436,-121.5702684009056,38.09822388148899,-121.60393055710335,38.10898488355559,-121.63051299143712,38.10154624398382,-121.6371124122602,38.08992846796019,-121.66657562158946,38.09834799503045,-121.68644943926694,38.08549239192541,-121.68354131427145,38.067767361744586,-121.6994337861218,38.051017879478934,-121.74477304125975,38.03062196596892,-121.80058061825645,38.025494545143545,-121.82947484737826,38.03754110345818,-121.83790479528182,38.06236660550297,-121.8533769712995,38.059398593007586,-121.83359162133019,38.0236317357714,-121.82191980051499,38.02152160869139,-121.8452383838121,37.99565135456487,-121.86590229836338,37.98235407021048,-121.87389402439265,37.949298472345106,-121.88361340562756,37.94069631819184,-121.86986600564887,37.929583865084055,-121.87272500251947,37.917601039061026,-121.88853686499493,37.912210873444394,-121.93679916804501,37.85678621415542,-121.88209073375492,37.84099142667992,-121.86810714523494,37.85399849645137,-121.85208152546818,37.83929578814087,-121.83044241300178,37.83564997147988,-121.8066090526221,37.81308303505659,-121.7922590016027,37.80782963818973,-121.76324145268939,37.7858900934321,-121.76527957768621,37.7773995799036,-121.73909092251853,37.760126577847075,-121.70685220486024,37.77253795491117,-121.69044629863572,37.761101645553936,-121.65209140390357,37.75944488930651,-121.66449931638431,37.74842932369859,-121.6507850361973,37.735751545593246,-121.65918360805927,37.72781387164724,-121.65894963201794,37.70730379459576,-121.63536538726288,37.70130697273004,-121.63448013830595,37.689717726914694,-121.61490015812797,37.67537787797863,-121.60974490188602,37.64429441552687,-121.6227430268658,37.63603342387307,-121.62601494873576,37.621678591603654,-121.61450599042024,37.59930529893006,-121.58214772276216,37.58058849166747,-121.5660067644539,37.54927187400773,-121.54111389574251,37.52994497299608,-121.50439590934116,37.525883816752355,-121.49308462915042,37.502441020955416,-121.48138812291859,37.505721846992,-121.46184374690722,37.53450626882233,-121.44088779485645,37.54675186776166,-121.42484409071466,37.54751497713545,-121.42580857821315,37.564976893775,-121.38028850640882,37.586133978117175,-121.36222241581186,37.603589127048394,-121.31597830859198,37.6093966551644,-121.2544957930624,37.65727026654844,-121.22158270248849,37.67257598423299,-121.22429523477598,37.68152568213577,-121.2057427212631,37.69569779461375,-121.16857574007076,37.70748815501213,-121.14110785782174,37.729918075810644,-121.11848947660684,37.73365946955482,-121.10911928703808,37.7484026966153,-121.09223503081427,37.74791053724107,-121.09480595685193,37.760903828887535,-121.05617153503692,37.76043123409664,-121.09747076830615,37.76801436220984,-121.15035315884904,37.79415341529426,-121.18449382754608,37.82583186628676,-121.19699943377668,37.826716714202064,-121.2195945576999,37.85136148083046,-121.26523294929575,37.87824116933041,-121.2947732367499,37.913431269275804,-121.271524724286,37.93996951090128,-121.19155812336845,37.95833420253945,-121.11637632452681,37.95492616608641,-121.10437461621211,37.957914906706776,-121.05944651211519,37.95597624525141,-121.0339739194464,37.94209255568967,-121.0166917559315,37.94320716193795,-121.00221693720397,37.95548945983552,-120.97566607266185,37.96720422856731,-120.97877787890707,37.989337251449626,-120.9583201601888,37.98447010979055,-120.940789375841,37.99810579518606,-120.92829857481871,38.01908881702849,-120.90450576548068,38.0272342086825,-120.91396404254931,38.035717584710994,-120.91473279150648,38.05371388572473,-120.95564168727628,38.05178600656103,-120.98212063202686,38.064245121125055,-121.03830712152296,38.03886609408113,-121.06709473606162,38.018101445155025,-121.1009083245508,38.00855445246151,-121.130640501588,38.008583444128135,-121.20277275251772,37.95955794732919,-121.28034443156395,37.99378153581773,-121.26629757012745,38.004894071217166,-121.2374627691305,38.01277404724658,-121.21825716395199,38.036504297209774,-121.1927208462833,38.05271741697629,-121.17248860464804,38.05317975343388,-121.1349351203313,38.074925166941796,-121.1088929182884,38.065759808622715,-121.08234508395464,38.050340206563305,-121.07683546104653,38.075894660690324,-121.06335145898413,38.08001638672556,-121.05341488399955,38.103619159605614,-121.02532235904312,38.11545590229554,-121.02185200800687,38.141849487671266,-120.99854338616802,38.13813815330201,-120.96777642579912,38.14682469287186,-120.9602597226858,38.1365514095545,-120.9325378352288,38.152037275155465,-120.90481372589687,38.15161844286445,-120.90117972173584,38.163558659512546,-120.8795133332278,38.16931939075363,-120.83793204891731,38.18877460322341,-120.83898908849903,38.19987750528952,-120.85724504159566,38.19074097717868,-120.87978625510237,38.18972461780527,-120.89379082070565,38.19927907508213,-120.9222689144114,38.1909182750951,-120.94590735812471,38.20575099590542,-120.97285543933293,38.20184120424483,-121.02143199238253,38.21228919277024",
            "HUC": "18040003"
        }
    }
}

Search Feature Translation Service for Exact HUC Matches

Here we can set a HUC ID, or hydrologic unit code, and use this to query the HUC FTS. By defining the parameter EXACT = True, we tell the query to not search for partial matches.

Based on the partial name response in the previous step, we can now do an exact search for San Joaquin River Basin, using its HUC ID (1804).

# Querying exact matches for HUC "1804" = San Joaquin River Basin

HUC = "1804"
EXACT = True

# Query Feature Translation Service and parse JSON response
r = requests.get("https://fts.podaac.earthdata.nasa.gov/huc/{}?exact={}".format(HUC, EXACT))

# Load response from FTS
response = r.json()

# Print only the region name from the query results of the HUC database
print(json.dumps(response["results"]["1804"]["Region Name"], indent = 4))
"San Joaquin"

Search Feature Translation Service for Exact HUC and Named Region Matches

What if we are interested in the Toulumne River Basin within the San Joaquin main basin? We can search directly for that basin as well. If we already know an exact region name or HUC in USGS’s Watershed Boundary Dataset (WBD), we can use this or the name of the basin, or search partially like we did above. Below is an example of searching by exact match using HUC ID (e.g. 18040009) that could be modified to search by region name (“Upper Tuolumne”).

# Querying exact matches with HUC "18040009" = Upper Tuolumne

HUC = "18040009" #or REGION = "Upper Tuolumne"
EXACT = True

# Query Feature Translation Service and parse JSON response
# If using region, Note the change in endpoint must go from "/huc" to "/region" and the .format() must change from HUC to REGION
r = requests.get("https://fts.podaac.earthdata.nasa.gov/huc/{}?exact={}".format(HUC, EXACT))

# Load response from FTS
response = r.json()

# Print all elements in HUC database that exactly match HUC "18040009"
print(json.dumps(response, indent = 4))
{
    "status": "200 OK",
    "time": "1.659 ms.",
    "hits": 1,
    "search on": {
        "parameter": "HUC",
        "exact": true,
        "polygon_format": "",
        "page_number": 1,
        "page_size": 100
    },
    "results": {
        "18040009": {
            "USGS Polygon": {
                "Object URL": "https://podaac-feature-translation-service.s3-us-west-2.amazonaws.com/18040009.zip",
                "Source": "ftp://rockyftp.cr.usgs.gov/vdelivery/Datasets/Staged/Hydrography/WBD/HU2/Shape/WBD_18_HU2_Shape.zip"
            },
            "Bounding Box": "-121.17476593797784,37.57291785522102,-119.19927543166921,38.22952896670182",
            "Convex Hull Polygon": "-121.105517801627,37.57291785522102,-120.51777999837259,37.58160878749919,-119.26845687218679,37.73942430183757,-119.26095827844847,37.741190162251485,-119.26079495969867,37.74128122475133,-119.25581474616479,37.7450598684955,-119.25563206491506,37.74520087891193,-119.25521361804067,37.745555179953044,-119.20452512020273,37.79316755800414,-119.20311483687158,37.794898117376476,-119.20297581291345,37.79511513091779,-119.20108320354137,37.801137019450096,-119.20096521291657,37.803876760070864,-119.19927543166921,37.88483115890352,-119.19931234937746,37.885001276611604,-119.20064394937538,37.88738135160793,-119.31090541587093,38.044980644071586,-119.3277000731365,38.0651666159153,-119.32796109605277,38.06544024091488,-119.34908448143665,38.08655395234041,-119.62508146642494,38.22905559795254,-119.65624842470987,38.22952896670182,-119.65829346949835,38.22947615316025,-119.79473757241158,38.21799358859471,-119.99491475022586,38.196920114669126,-120.38613654232694,38.056378609678916,-121.15444382863438,37.62884831659255,-121.15500076925849,37.6284224540932,-121.15993039529252,37.62332076451776,-121.16822139007132,37.61386883849076,-121.17452907235321,37.605445134337174,-121.17462853797804,37.60522817287921,-121.17469632131127,37.60502320725453,-121.17471004943627,37.60496802808791,-121.17476593797784,37.604743358296616,-121.17472602131124,37.60443736142207,-121.1743974786034,37.603737121839856,-121.17385444318757,37.603213931215635,-121.12495024430518,37.575249448967384,-121.1206057318119,37.57340581772024,-121.1184699109819,37.573299354178744,-121.105517801627,37.57291785522102",
            "Visvalingam Polygon": "-119.65612154137676,38.229472830243594,-119.65887392887248,38.21611789588928,-119.68748882882807,38.20072575945488,-119.74423195478164,38.21583016359807,-119.79473757241158,38.21799358859471,-119.80777226405803,38.20387888444998,-119.83634931818034,38.19900379279085,-119.8794751608217,38.205164957364616,-119.92926093053609,38.1903575073876,-119.95874486382365,38.194300821964816,-119.9915583491894,38.18745202718378,-119.99491475022586,38.196920114669126,-120.05974666158357,38.15445730952666,-120.10528053234623,38.13442047414111,-120.12843912918527,38.10262073148215,-120.20521266552441,38.056065841971076,-120.26427926855774,38.061807551337154,-120.34283367885251,38.04442165553081,-120.36616220485797,38.05864021280041,-120.38138515275097,38.04379106074015,-120.39399451523144,38.00852514516987,-120.41557226103123,38.00413815246833,-120.4432863495299,37.97081393481176,-120.45616958284324,37.92842260675252,-120.46878266719864,37.921885701554345,-120.4624829120001,37.891430354726594,-120.479954646348,37.871879250590325,-120.48053337030541,37.82415609128935,-120.5431307066666,37.84913992354228,-120.55227857644405,37.86382160997783,-120.57047251079081,37.845455260006304,-120.5664340514221,37.82240133087544,-120.59755003054045,37.81161053401718,-120.64595511379866,37.78181727677179,-120.67580313979397,37.7973594465393,-120.7399643115694,37.77691864136273,-120.75337800946522,37.73604807163446,-120.78855502295232,37.75464512473059,-120.82306428227372,37.739964848711736,-120.82298294894053,37.72367104352867,-120.84114918537068,37.706087340431,-120.8673865186633,37.69917305085835,-120.87598703427494,37.68470263317249,-120.91724289983591,37.65975447800287,-120.94840845082916,37.657548763422994,-121.0014800642885,37.642007069697115,-121.06141474752877,37.632796530128076,-121.15500076925849,37.6284224540932,-121.17472602131124,37.60443736142207,-121.15475178384224,37.60555392496201,-121.12649717971942,37.5761612791743,-121.105517801627,37.57291785522102,-121.06195388086127,37.58432554999496,-121.051833277752,37.59549621664428,-120.9623811789325,37.616090631195675,-120.93801052688701,37.61182627286894,-120.86057590200721,37.62129079368759,-120.85730386034561,37.613155902033554,-120.78087282192257,37.61414406661538,-120.73817309594716,37.63053679471494,-120.70606299078867,37.6253131207647,-120.65312547628753,37.630845649922776,-120.64372085026048,37.617530275985075,-120.59897548366325,37.61838293640045,-120.58566304618392,37.6280897895104,-120.55437374519079,37.61949203744041,-120.53035751501977,37.62416281034979,-120.52267756711501,37.58373637916253,-120.47482846302262,37.59087335206817,-120.45815308909016,37.620518593688814,-120.4371221932895,37.63718915616295,-120.3849402642038,37.635048797832894,-120.3755883360933,37.65339462697108,-120.39417890064777,37.66818361028146,-120.392313883984,37.68359100504921,-120.3559603048738,37.67552716860342,-120.32610607262848,37.648966585311314,-120.30639988828403,37.66573735924362,-120.3455439350983,37.72512544352645,-120.31539807993676,37.733894229971156,-120.28665821956469,37.72927809560332,-120.28245683519623,37.74541342682829,-120.26069274460497,37.73358365601331,-120.25387803732389,37.749232223697334,-120.200135472824,37.76372567054983,-120.17357968640687,37.79608365070794,-120.12741327606187,37.78170633927192,-120.08906888341306,37.81273366005712,-120.07891344384547,37.82866939649068,-120.05533048450707,37.812757440265386,-120.02518823247055,37.81132716005931,-119.96359235131615,37.78073240906514,-119.94507216905322,37.76542058617224,-119.90693944932076,37.75781682576735,-119.86549272230178,37.77222938512,-119.85359450461186,37.758767389307536,-119.83160174943771,37.76963435595735,-119.80589665676928,37.75608133722835,-119.75060675164673,37.77341942574316,-119.7359645225028,37.78635874968137,-119.6978660861036,37.78960109342637,-119.64907657576265,37.81516770484501,-119.65722697262504,37.83230492565173,-119.59708603105173,37.86135878810666,-119.58892104668939,37.88872669535584,-119.57247042275657,37.8998297015886,-119.53527651760601,37.90190377762701,-119.49696578120711,37.86409281310239,-119.47533168332404,37.85892923602705,-119.45447817606475,37.871394138091034,-119.44539026566218,37.858937875610366,-119.4045319969756,37.85021429541558,-119.40293857510306,37.833821247524384,-119.37314428244099,37.83849664855876,-119.35155096789117,37.82452854545545,-119.3552763335104,37.812805713182,-119.32340220126821,37.79368655279501,-119.29229722319144,37.762878678884476,-119.2876598648653,37.74535544245333,-119.26052065344913,37.74159433725089,-119.24428567430766,37.76834668616766,-119.22055414726117,37.77924966531742,-119.20108320354137,37.801137019450096,-119.21738830351609,37.8183151860901,-119.20449054936944,37.82981189961396,-119.21625690560114,37.847411426669964,-119.21512584414461,37.87042564434256,-119.19927543166921,37.88483115890352,-119.23787860140095,37.911280908862466,-119.26486444510903,37.91263911719369,-119.26807310656238,37.92880876300194,-119.30948290962311,37.94616478068332,-119.31574230232172,37.96621302648555,-119.30533157629623,38.02416955035392,-119.34927245018639,38.08565116171684,-119.35845034913046,38.08266815651314,-119.39810467927725,38.1068175096006,-119.43127595110076,38.11332130542388,-119.4403859021283,38.09636985024184,-119.46399499479998,38.09838383773871,-119.4692413104168,38.12798441894279,-119.48819819267908,38.132729004352086,-119.50246159786525,38.159339980352456,-119.50459633952858,38.140964939755975,-119.54763344883679,38.14419101891764,-119.54624260196397,38.15397065015242,-119.5773162810824,38.15780512931315,-119.57980050712018,38.17791634178195,-119.62908996641869,38.196015076128845,-119.62508146642494,38.22905559795254,-119.65612154137676,38.229472830243594",
            "Region Name": "Upper Tuolumne"
        }
    }
}

Visualize the Response from the HUC Feature Translation Service

Function for Visualization

Below is a function created specifically to visualize the output of the HUC Feature Translation Service.

def visualize(fts_response):
    
    regions = []
    bounding_boxes = []
    convex_hull_polygons = []
    visvalingam_polygons = []
    for element in fts_response['results']:
        for heading in fts_response['results'][element]:
            if heading == "Bounding Box":
                bounding_boxes.append([float(e) for e in fts_response['results'][element][heading].split(",")])
            elif heading == "Convex Hull Polygon":
                convex_hull_polygons.append([float(e) for e in fts_response['results'][element][heading].split(",")])
            elif heading == "Visvalingam Polygon":
                visvalingam_polygons.append([float(e) for e in fts_response['results'][element][heading].split(",")])
            elif heading == "HUC":
                regions.append("Region Name: " + element + "\n" + "HUC: " + fts_response['results'][element][heading])
            elif heading == "Region Name":
                regions.append("Region Name: " + fts_response['results'][element][heading] + "\n" + "HUC: " + element)
            else:
                continue

    bounding_boxes = [box(e[0], e[1], e[2], e[3]) for e in bounding_boxes]
    convex_hull_polygons = [Polygon(np.asarray(polygon).reshape(-1,2)) for polygon in convex_hull_polygons]
    visvalingam_polygons = [Polygon(np.asarray(polygon).reshape(-1,2)) for polygon in visvalingam_polygons]
    
    for i in range(len(bounding_boxes)):
        ax = gpd.GeoSeries(bounding_boxes[i]).plot(alpha=0.2, cmap='Pastel1', figsize=(10,10))
        gpd.GeoSeries(convex_hull_polygons[i]).plot(ax = ax, cmap='Pastel2')
        gpd.GeoSeries(visvalingam_polygons[i]).plot(alpha=0.5, ax=ax, cmap='viridis')

        plt.title(regions[i])
        plt.show()

Visualization

We can take that response and pass it to the visualize() function created above. The pink polygon is Bounding Box, the green is Convex Hull Polygon and the purple color is Visvalingam Polygon

#visualize FTS response
visualize(response)

Query Data by Bounding Box

We can use results obtained from the FTS to then directly and automatically query on data using the earthaccess Python library. We use the bounding box representing Upper Tuolumne River Basin extracted from the response above, and search for granules available from the SWOT mission, as an example.

shortname = 'SWOT_L2_HR_Raster_2.0' # SWOT Raster files
HUC = "18040009"

# Obtain bounding box from response
bbox = response['results'][HUC]['Bounding Box']
bbox_vals = []
for val in bbox.split(','): bbox_vals.append(float(val)) #transform string into values

# Query data by bounding box
results = earthaccess.search_data(short_name=shortname, bounding_box=(bbox_vals[0],bbox_vals[1],bbox_vals[2],bbox_vals[3]))
Granules found: 84

Query Data by Polygon

Instead of querying via bounding box from the FTS response, we can extract the polygon of the region and use this to query.

shortname = 'SWOT_L2_HR_Raster_2.0' # SWOT Raster files
HUC = "18040009"

#obtain polygon from response
polygon_v = response['results'][HUC]['Visvalingam Polygon']

#transform string into list of values
polygon_vals = []
for val in polygon_v.split(','): polygon_vals.append(float(val)) 
#change list to correct tuple format to input into earthaccess query
it = iter(polygon_vals)
poly = [(x, next(it)) for x in it]

# Query by polygon
results = earthaccess.search_data(short_name=shortname, polygon=poly)
Granules found: 70